From b6cfe35940ac9648508b149931cb4ad672469876 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Luk=C3=A1=C5=A1=20Tyrychtr?= Date: Fri, 16 Sep 2022 18:48:40 +0200 Subject: [PATCH] Style fixes Documentation and coding style updates. --- gtk/a11y/gtkatspicontext.c | 5 +++-- gtk/gtkaccessible.c | 46 ++++++++++++++++++++------------------ gtk/gtkaccessible.h | 23 ++++++++++++++----- gtk/gtkstack.c | 22 ++++++++++++------ gtk/gtkwidget.c | 8 +++---- 5 files changed, 64 insertions(+), 40 deletions(-) diff --git a/gtk/a11y/gtkatspicontext.c b/gtk/a11y/gtkatspicontext.c index 67d9623ece..e2988252de 100644 --- a/gtk/a11y/gtkatspicontext.c +++ b/gtk/a11y/gtkatspicontext.c @@ -85,7 +85,7 @@ * * These are the exceptions implemented by GTK itself, but note that application * developers can customize the accessibility tree by implementing the - * GtkAccessible interface in any way they choose. + * [iface@Gtk.Accessible] interface in any way they choose. */ struct _GtkAtSpiContext @@ -333,7 +333,8 @@ collect_relations (GtkAtSpiContext *self, /* }}} */ /* {{{ Accessible implementation */ static int -get_index_in (GtkAccessible *parent, GtkAccessible *child) +get_index_in (GtkAccessible *parent, + GtkAccessible *child) { GtkAccessible *candidate; int res; diff --git a/gtk/gtkaccessible.c b/gtk/gtkaccessible.c index a3a05acd56..7468b8950e 100644 --- a/gtk/gtkaccessible.c +++ b/gtk/gtkaccessible.c @@ -37,11 +37,11 @@ * a way that should be reflected by assistive technologies. For instance, * if a `GtkWidget` visibility changes, the %GTK_ACCESSIBLE_STATE_HIDDEN * state will also change to reflect the [property@Gtk.Widget:visible] property. - * + * * Every accessible implementation is part of a tree of accessible objects. * Normally, this tree corresponds to the widget tree, but can be customized - * by reimplementing the #GtkAccessibleInterface.get_parent() - * and #GtkAccessibleInterface.get_child_at_index() methods. + * by reimplementing the [vfunc@Gtk.Accessible.get_parent] + * and [vfunc@Gtk.Accessible.get_child_at_index] virtual functions. * Note that you can not create a top-level accessible object as of now, * which means that you must always have a parent accessible object. */ @@ -81,7 +81,7 @@ gtk_accessible_default_init (GtkAccessibleInterface *iface) g_object_interface_install_property (iface, pspec); } -/* +/** * gtk_accessible_get_at_context: * @self: a `GtkAccessible` * @@ -103,7 +103,7 @@ gtk_accessible_get_at_context (GtkAccessible *self) * * Retrieves the parent `GtkAccessible` for the given `GtkAccessible`. * - * Returns: (transfer none): the parent `GtkAccessible` or NULL, if we this is the root + * Returns: (transfer none): the parent `GtkAccessible`, which can not be %NULL */ GtkAccessible * gtk_accessible_get_parent (GtkAccessible *self) @@ -114,21 +114,23 @@ gtk_accessible_get_parent (GtkAccessible *self) } -/* +/** * gtk_accessible_get_child_at_index: * @self: a `GtkAccessible` - * @index: the index of the child to get + * @idx: the index of the child to get * * Retrieves the child `GtkAccessible` for this `GtkAccessible` with the given @index. * - * Returns: (transfer none): the child `GtkAccessible` with the given @index or NULL if the index is outside range + * Returns: (transfer none) (nullable): the child `GtkAccessible` with the given @index or %NULL if the index is outside range + * + * since: 4.10 */ GtkAccessible * -gtk_accessible_get_child_at_index (GtkAccessible *self, guint index) +gtk_accessible_get_child_at_index (GtkAccessible *self, guint idx) { g_return_val_if_fail (GTK_IS_ACCESSIBLE (self), NULL); - return GTK_ACCESSIBLE_GET_IFACE (self)->get_child_at_index (self, index); + return GTK_ACCESSIBLE_GET_IFACE (self)->get_child_at_index (self, idx); } /** @@ -700,10 +702,10 @@ gtk_accessible_role_to_name (GtkAccessibleRole role, /*< private > * gtk_accessible_role_is_range_subclass: * @role: a `GtkAccessibleRole` - * + * * Checks if @role is considered to be a subclass of %GTK_ACCESSIBLE_ROLE_RANGE * according to the WAI-ARIA specification. - * + * * Returns: whether the @role is range-like */ gboolean @@ -762,7 +764,7 @@ gtk_accessible_platform_changed (GtkAccessible *self, gtk_at_context_update (context); } -/* +/** * gtk_accessible_get_platform_state: * @self: a `GtkAccessible` * @state: platform state to query @@ -784,7 +786,7 @@ gtk_accessible_get_platform_state (GtkAccessible *self, return GTK_ACCESSIBLE_GET_IFACE (self)->get_platform_state (self, state); } -/* +/** * gtk_accessible_bounds_changed: * @self: a `GtkAccessible` * @@ -814,20 +816,20 @@ gtk_accessible_bounds_changed (GtkAccessible *self) /* * gtk_accessible_get_bounds: * @self: a `GtkAccessible` - * @x: the x coordinate of the top left corner of the accessible - * @y: the y coordinate of the top left corner of the widget - * @width: the width of the widget - * @height: the height of the widget - * - * Query the coordinates and dimensions of this accessible + * @x: (out): the x coordinate of the top left corner of the accessible + * @y: (out): the y coordinate of the top left corner of the widget + * @width: (out): the width of the accessible object + * @height: (out): the height of the accessible object * - * See gtk_accessible_bounds_changed(). + * Queries the coordinates and dimensions of this accessible * * This functionality can be overridden by `GtkAccessible` * implementations, e.g. to get the bounds from an ignored * child widget. * - * Returns: whether the bounds should be considered valid + * Returns: true if the bounds are valid, and false otherwise + * + * Since: 4.10 */ gboolean gtk_accessible_get_bounds (GtkAccessible *self, diff --git a/gtk/gtkaccessible.h b/gtk/gtkaccessible.h index 36b3f08cb0..2f4c9c8a6f 100644 --- a/gtk/gtkaccessible.h +++ b/gtk/gtkaccessible.h @@ -37,9 +37,14 @@ G_DECLARE_INTERFACE (GtkAccessible, gtk_accessible, GTK, ACCESSIBLE, GObject) /** * GtkAccessiblePlatformState: + * @GTK_ACCESSIBLE_PLATFORM_STATE_FOCUSABLE: whether the accessible can be focused + * @GTK_ACCESSIBLE_PLATFORM_STATE_FOCUSED: whether the accessible has focus + * @GTK_ACCESSIBLE_PLATFORM_STATE_ACTIVE: whether the accessible is active * * The various platform states which can be queried - * using @gtk_accessible_get_platform_state + * using [method@Gtk.Accessible.get_platform_state]. + * + * Since: 4.10 */ typedef enum { GTK_ACCESSIBLE_PLATFORM_STATE_FOCUSABLE, @@ -49,9 +54,17 @@ typedef enum { /** * GtkAccessiblePlatformChange: + * @GTK_ACCESSIBLE_PLATFORM_CHANGE_FOCUSABLE: whether the accessible has changed + * its focusable state + * @GTK_ACCESSIBLE_PLATFORM_CHANGE_FOCUSED: whether the accessible has changed its + * focused state + * @GTK_ACCESSIBLE_PLATFORM_CHANGE_ACTIVE: whether the accessible has changed its + * active state * * Represents the various platform changes which can occur and are communicated - * using @gtk_accessible_platform_changed. + * using [method@Gtk.Accessible.platform_changed]. + * + * Since: 4.10 */ typedef enum { GTK_ACCESSIBLE_PLATFORM_CHANGE_FOCUSABLE = 1 << GTK_ACCESSIBLE_PLATFORM_STATE_FOCUSABLE, @@ -97,12 +110,12 @@ struct _GtkAccessibleInterface /** * GtkaccessibleInterface::get_child_at_index: * @self: a `GtkAccessible` - * @index: the index of the child + * @idx: the index of the child * * Returns the child of @self whose position corresponds to @index. * If @index is not valid for @self's children, return -1. */ - GtkAccessible * (* get_child_at_index) (GtkAccessible *self, guint index); + GtkAccessible * (* get_child_at_index) (GtkAccessible *self, guint idx); /** * GtkAccessibleInterface::get_bounds: @@ -135,7 +148,7 @@ GDK_AVAILABLE_IN_ALL GtkAccessible * gtk_accessible_get_parent(GtkAccessible *self); GDK_AVAILABLE_IN_ALL -GtkAccessible * gtk_accessible_get_child_at_index(GtkAccessible *self, guint index); +GtkAccessible * gtk_accessible_get_child_at_index(GtkAccessible *self, guint idx); GDK_AVAILABLE_IN_ALL gboolean gtk_accessible_get_bounds (GtkAccessible *self, int *x, int *y, int *width, int *height); diff --git a/gtk/gtkstack.c b/gtk/gtkstack.c index b43950725e..d02cf8aca7 100644 --- a/gtk/gtkstack.c +++ b/gtk/gtkstack.c @@ -257,27 +257,35 @@ gtk_stack_page_accessible_get_platform_state (GtkAccessible *self, } static GtkAccessible * -gtk_stack_page_accessible_get_parent (GtkAccessible *accessible) { +gtk_stack_page_accessible_get_parent (GtkAccessible *accessible) +{ GtkStackPage *page = GTK_STACK_PAGE (accessible); if (page->widget == NULL) return NULL; else - return GTK_ACCESSIBLE (gtk_widget_get_parent (page->widget)); + return GTK_ACCESSIBLE (gtk_widget_get_parent (page->widget)); } static GtkAccessible * -gtk_stack_page_accessible_get_child_at_index(GtkAccessible *accessible, guint index) { +gtk_stack_page_accessible_get_child_at_index(GtkAccessible *accessible, + guint idx) +{ GtkStackPage *page = GTK_STACK_PAGE (accessible); - if (index == 0 && page->widget != NULL) + if (idx == 0 && page->widget != NULL) return GTK_ACCESSIBLE (page->widget); else return NULL; } static gboolean -gtk_stack_page_accessible_get_bounds (GtkAccessible *accessible, int *x, int *y, int *width, int *height) { +gtk_stack_page_accessible_get_bounds (GtkAccessible *accessible, + int *x, + int *y, + int *width, + int *height) +{ GtkStackPage *page = GTK_STACK_PAGE (accessible); if (page->widget != NULL) return gtk_accessible_get_bounds (GTK_ACCESSIBLE (page->widget), x, y, width, height); @@ -768,11 +776,11 @@ gtk_stack_buildable_interface_init (GtkBuildableIface *iface) } static GtkAccessible * -gtk_stack_accessible_get_child_at_index (GtkAccessible *accessible, guint index) +gtk_stack_accessible_get_child_at_index (GtkAccessible *accessible, guint idx) { GtkStack *stack = GTK_STACK (accessible); GtkStackPrivate *priv = gtk_stack_get_instance_private (stack); - GtkStackPage *page = g_ptr_array_index (priv->children, index); + GtkStackPage *page = g_ptr_array_index (priv->children, idx); return GTK_ACCESSIBLE (page); } diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c index 115bef5826..5694974a35 100644 --- a/gtk/gtkwidget.c +++ b/gtk/gtkwidget.c @@ -8473,17 +8473,17 @@ gtk_widget_accessible_get_parent (GtkAccessible *self) static GtkAccessible * gtk_widget_accessible_get_child_at_index (GtkAccessible *self, - guint index) + guint idx) { - guint idx = 0; + guint i = 0; GtkWidget *child; for (child = gtk_widget_get_first_child (GTK_WIDGET (self)); child != NULL; child = gtk_widget_get_next_sibling (child)) { - if (idx == index) + if (i == idx) return GTK_ACCESSIBLE (child); - idx++; + i++; } return NULL; } -- 2.30.2